/*
 * $HeadURL: http://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/impl/client/ClientParamsStack.java $
 * $Revision: 673450 $
 * $Date: 2008-07-02 10:35:05 -0700 (Wed, 02 Jul 2008) $
 *
 * ====================================================================
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 * ====================================================================
 *
 * This software consists of voluntary contributions made by many
 * individuals on behalf of the Apache Software Foundation.  For more
 * information on the Apache Software Foundation, please see
 * <http://www.apache.org/>.
 *
 */

package org.apache.http.impl.client;

import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
import org.apache.http.params.AbstractHttpParams;
import org.apache.http.params.HttpParams;

/**
 * Represents a stack of parameter collections. When retrieving a parameter, the
 * stack is searched in a fixed order and the first match returned. Setting
 * parameters via the stack is not supported. To minimize overhead, the stack
 * has a fixed size and does not maintain an internal array. The supported stack
 * entries, sorted by increasing priority, are:
 * <ol>
 * <li>Application parameters: expected to be the same for all clients used by
 * an application. These provide "global", that is application-wide, defaults.</li>
 * <li>Client parameters: specific to an instance of
 * {@link org.apache.http.client.HttpClient HttpClient}. These provide client
 * specific defaults.</li>
 * <li>Request parameters: specific to a single request execution. For
 * overriding client and global defaults.</li>
 * <li>Override parameters: specific to an instance of
 * {@link org.apache.http.client.HttpClient HttpClient}. These can be used to
 * set parameters that cannot be overridden on a per-request basis.</li>
 * </ol>
 * Each stack entry may be <code>null</code>. That is preferable over an empty
 * params collection, since it avoids searching the empty collection when
 * looking up parameters.
 * 
 * @author <a href="mailto:rolandw at apache.org">Roland Weber</a>
 * 
 * 
 * @version $Revision: 673450 $
 */
public class ClientParamsStack extends AbstractHttpParams {

    private final Log log = LogFactory.getLog(getClass());

    /** The application parameter collection, or <code>null</code>. */
    protected final HttpParams applicationParams;

    /** The client parameter collection, or <code>null</code>. */
    protected final HttpParams clientParams;

    /** The request parameter collection, or <code>null</code>. */
    protected final HttpParams requestParams;

    /** The override parameter collection, or <code>null</code>. */
    protected final HttpParams overrideParams;

    /**
     * Creates a new parameter stack from elements. The arguments will be stored
     * as-is, there is no copying to prevent modification.
     * 
     * @param aparams
     *            application parameters, or <code>null</code>
     * @param cparams
     *            client parameters, or <code>null</code>
     * @param rparams
     *            request parameters, or <code>null</code>
     * @param oparams
     *            override parameters, or <code>null</code>
     */
    public ClientParamsStack(HttpParams aparams, HttpParams cparams,
            HttpParams rparams, HttpParams oparams) {
        applicationParams = aparams;
        clientParams = cparams;
        requestParams = rparams;
        overrideParams = oparams;
    }

    /**
     * Creates a copy of a parameter stack. The new stack will have the exact
     * same entries as the argument stack. There is no copying of parameters.
     * 
     * @param stack
     *            the stack to copy
     */
    public ClientParamsStack(ClientParamsStack stack) {
        this(stack.getApplicationParams(), stack.getClientParams(), stack
                .getRequestParams(), stack.getOverrideParams());
    }

    /**
     * Creates a modified copy of a parameter stack. The new stack will contain
     * the explicitly passed elements. For elements where the explicit argument
     * is <code>null</code>, the corresponding element from the argument stack
     * is used. There is no copying of parameters.
     * 
     * @param stack
     *            the stack to modify
     * @param aparams
     *            application parameters, or <code>null</code>
     * @param cparams
     *            client parameters, or <code>null</code>
     * @param rparams
     *            request parameters, or <code>null</code>
     * @param oparams
     *            override parameters, or <code>null</code>
     */
    public ClientParamsStack(ClientParamsStack stack, HttpParams aparams,
            HttpParams cparams, HttpParams rparams, HttpParams oparams) {
        this((aparams != null) ? aparams : stack.getApplicationParams(),
                (cparams != null) ? cparams : stack.getClientParams(),
                (rparams != null) ? rparams : stack.getRequestParams(),
                (oparams != null) ? oparams : stack.getOverrideParams());
    }

    /**
     * Obtains the application parameters of this stack.
     * 
     * @return the application parameters, or <code>null</code>
     */
    public final HttpParams getApplicationParams() {
        return applicationParams;
    }

    /**
     * Obtains the client parameters of this stack.
     * 
     * @return the client parameters, or <code>null</code>
     */
    public final HttpParams getClientParams() {
        return clientParams;
    }

    /**
     * Obtains the request parameters of this stack.
     * 
     * @return the request parameters, or <code>null</code>
     */
    public final HttpParams getRequestParams() {
        return requestParams;
    }

    /**
     * Obtains the override parameters of this stack.
     * 
     * @return the override parameters, or <code>null</code>
     */
    public final HttpParams getOverrideParams() {
        return overrideParams;
    }

    /**
     * Obtains a parameter from this stack. See class comment for search order.
     * 
     * @param name
     *            the name of the parameter to obtain
     * 
     * @return the highest-priority value for that parameter, or
     *         <code>null</code> if it is not set anywhere in this stack
     */
    public Object getParameter(String name) {
        if (name == null) {
            throw new IllegalArgumentException(
                    "Parameter name must not be null.");
        }

        Object result = null;

        if (overrideParams != null) {
            result = overrideParams.getParameter(name);
        }
        if ((result == null) && (requestParams != null)) {
            result = requestParams.getParameter(name);
        }
        if ((result == null) && (clientParams != null)) {
            result = clientParams.getParameter(name);
        }
        if ((result == null) && (applicationParams != null)) {
            result = applicationParams.getParameter(name);
        }
        if (this.log.isDebugEnabled()) {
            this.log.debug("'" + name + "': " + result);
        }

        return result;
    }

    /**
     * Does <i>not</i> set a parameter. Parameter stacks are read-only. It is
     * possible, though discouraged, to access and modify specific stack
     * entries. Derived classes may change this behavior.
     * 
     * @param name
     *            ignored
     * @param value
     *            ignored
     * 
     * @return nothing
     * 
     * @throws UnsupportedOperationException
     *             always
     */
    public HttpParams setParameter(String name, Object value)
            throws UnsupportedOperationException {

        throw new UnsupportedOperationException(
                "Setting parameters in a stack is not supported.");
    }

    /**
     * Does <i>not</i> remove a parameter. Parameter stacks are read-only. It is
     * possible, though discouraged, to access and modify specific stack
     * entries. Derived classes may change this behavior.
     * 
     * @param name
     *            ignored
     * 
     * @return nothing
     * 
     * @throws UnsupportedOperationException
     *             always
     */
    public boolean removeParameter(String name) {
        throw new UnsupportedOperationException(
                "Removing parameters in a stack is not supported.");
    }

    /**
     * Does <i>not</i> copy parameters. Parameter stacks are lightweight
     * objects, expected to be instantiated as needed and to be used only in a
     * very specific context. On top of that, they are read-only. The typical
     * copy operation to prevent accidental modification of parameters passed by
     * the application to a framework object is therefore pointless and
     * disabled. Create a new stack if you really need a copy. <br/>
     * Derived classes may change this behavior.
     * 
     * @return <code>this</code> parameter stack
     */
    public HttpParams copy() {
        return this;
    }

}
